建立 Astro 專案時，Node 與套件版本要怎麼管理？

2026 iThome 鐵人賽

DAY 2

Modern Web

用 Astro 打造 Content-first 前端網站：30 天從靜態內容到會員、資料庫與選型系列第 2 篇

18th鐵人賽

stca

2026-08-04 05:28:25

75 瀏覽

分享至

建立 Astro 專案前，先確認本機的 Node 符合 Astro 要求，再執行 npm create astro@latest。專案建立後，Astro 與其他套件會寫進 package.json，npm 也會產生 package-lock.json。

Node 是執行 Astro 的環境，Astro、Vue 和部署 adapter 則是安裝在專案裡的 npm 套件。選定框架支援的 Node 後，把套件安裝結果留在 lockfile，並讓本機、CI 與部署環境使用相同設定。

還在判斷 Astro 是否適合內容站，可以先看 Day 1：為什麼前端工程師要重新看 Astro？。本篇接在那個決定之後，處理環境、安裝流程與版本管理。

先確認 Node，再建立專案

Astro 7 目前要求 Node 22.12.0 以上，也不支援奇數版 Node。先檢查本機版本：

node --version

這個實作專案使用 Node 24.16.0，是 LTS，也符合 Astro 7 的要求。確認 Node 版本後，再啟動官方 CLI 精靈：

npm create astro@latest

精靈會詢問專案目錄、起始模板、是否安裝依賴，以及是否初始化 Git。它可以直接建立新目錄，不必事先準備空資料夾。若要使用官方範例，或在建立時加入 integration，可以直接寫在指令裡：

# 使用官方範例
npm create astro@latest -- --template <example-name>

# 建立時加入 Vue integration
npm create astro@latest -- --add vue

@latest 只決定這次新專案使用的 create-astro 版本，不會影響已存在的專案。若要重現本系列的實作結果，直接用 app-steps 的 step-02 commit，裡面已經有對應的 package.json 與 lockfile。

建立完成後，先確認開發伺服器與正式建置都能執行：

cd <project-name>
npm run dev
# 停止開發伺服器後，再驗正式建置
npm run build

本節依 Astro Install 官方文件查證，基準為 Astro 7，查證日為 2026-08-02。

專案建立後，這三個檔案各自記錄什麼

Astro 規定支援的 Node 範圍，專案再從中選一個實際使用的版本；Astro 本身和其他套件的版本則由 npm 管理。這些資訊分別記在以下檔案：

檔案	記錄的內容	這個專案的例子
`.nvmrc`	使用 nvm 時要切換的 Node 版本	`24.16.0`
`package.json`	Node 支援範圍、直接依賴及其允許版本	Node `>=22.12.0`、Astro `^7.1.1`
`package-lock.json`	npm 實際解析出的完整依賴樹	Astro `7.1.1`、Vite `8.1.5`

這個專案的設定如下：

# .nvmrc
24.16.0

// package.json
{
  "engines": {
    "node": ">=22.12.0"
  },
  "dependencies": {
    "astro": "^7.1.1"
  }
}

engines 表示專案接受的 Node 範圍，.nvmrc 則記錄這個 repo 實際驗證的版本。真正執行專案的，是 node --version 顯示的那個 Node。.nvmrc 由 nvm 使用，Astro 不會主動讀取；只有執行 nvm use，或在 shell 設定自動切換後，nvm 才會依檔案切換版本。完整行為可查 nvm 的 .nvmrc 文件。

package.json 的 ^7.1.1 允許 npm 在 Astro 7 的相容範圍內解析版本，lockfile 則記錄實際安裝的完整套件樹。目前 lockfile 中的 Astro 是 7.1.1。這兩個檔案都要進 Git；新增或更新套件時，也要一併檢查兩者的變更。package-lock.json 由 npm 維護，不需要手動修改。

平常開發不需要一直重新選版本

日常開發同一個專案時，通常直接執行 npm run dev。第一次在某台機器 clone 專案時，若使用 nvm，可以依序執行：

nvm install
npm ci
npm run build

nvm install 會依 .nvmrc 安裝並切換 Node；之後回到專案時，只要執行 nvm use。沒有使用 nvm 時，以其他版本管理方式準備相容的 Node 版本，並用 node --version 確認。CI 與部署平台也要指定相同的 Node 版本，再執行 npm ci。

npm ci 會先清除既有的 node_modules，再完全依照 lockfile 安裝；若 package.json 與 lockfile 不一致，npm ci 會直接失敗，也不會改寫兩份檔案。只有新增、移除或更新套件時，才使用對應的 npm install 指令，並把 package.json 與 lockfile 的變更一起提交。

npm 官方文件也說明，當 lockfile 裡的版本符合 package.json 範圍時，不帶參數的 npm install 會沿用 lockfile 的精確版本。因此 registry 出現新版，不會讓既有專案在下一次安裝時無條件跳版；升級仍然需要明確改動依賴。相關行為可查 npm install與 npm ci文件。

決定升級時，重新檢查相容性

這個 repo 曾把 Astro 從 6.4.3 升到 7.1.1。Git 紀錄中的主要變更如下：

項目	升級前	升級後
Astro	6.4.3	7.1.1
Cloudflare adapter	13.6.1	14.1.3
Vue integration	6.0.1	7.0.1
Vite	7	8

Astro 6 原本就已要求 Node >=22.12.0。升到 Astro 7 時，這個 repo 同時新增 .nvmrc，方便開發者切到已驗證的 Node 24.16.0；框架的最低門檻並沒有在這次升級中再次提高。

Astro 7 改用 Vite 8。Astro 官方的 v7 upgrade guide 提醒，使用 Vite plugin、config 或 Vite API 的專案，要另外查 Vite 8 migration guide。這個專案的 astro.config.mjs 沒有自訂 Vite plugin，也沒有改動 Vite config，所以這條提醒不影響它；乾淨安裝後，build、preview 與 Day 8：Vue island 都通過驗證，因此不需要修改頁面程式碼。

Astro 7 也移除了 @astrojs/db。這個專案當時尚未安裝或實作 Astro DB，因此既有功能沒有受到影響；只需調整後續資料層的選擇，實作見 Day 22：Drizzle ORM 與 Turso。已經使用 Astro DB 的專案要先評估資料遷移，也可以暫時留在 Astro 6。

決定升級後，照這個順序檢查

安排升級前，先確認這次要取得哪些新版功能、安全修正或部署平台支援，並留意既有版本何時停止維護。開始升級後，依序檢查：

執行 node --version 和 npm exec astro -- --version，記下目前能工作的環境。
閱讀目標版本的 Upgrade guide 與 changelog，先找 Node、adapter、integration 和已使用 API 的變動。
Astro 官方 integration 要和核心一起檢查。升到最新版本可以直接跑 npx @astrojs/upgrade；若要指定版本，則手動更新相關套件與 lockfile。關於 integration、adapter 與 Vite plugin 的分工，可接著看 Day 27：Integrations 與 Config。
檢查 package.json 與 package-lock.json 的 diff，確認沒有夾帶無關套件。
從乾淨安裝開始，執行 build、測試與部署預覽，再檢查原本的頁面和互動。